feat: zod v4 with backwards compatibility for v3.25+ #1040
Conversation
|
Update: Merge conflicts resolved. 1.20.2-next.0 published under @socotra/modelcontextprotocol-sdk Update 10/31: Updated to 1.21.0 and released under @socotra/modelcontextprotocol-sdk |
|
any info when we should expect this PR to merge? 🤔 |
|
This PR cannot land soon enough. |
|
publishing a 3.25.x for |
| "raw-body": "^3.0.0", | ||
| "zod": "^3.23.8", | ||
| "zod-to-json-schema": "^3.24.1" | ||
| "zod": "^3.25 || ^4.0" |
There was a problem hiding this comment.
For the Anthropic team: Zod 3.25 was a minor release with no breaking changes from Zod 3.24. It did however introduce a pre-release version of Zod 4 at the "zod/v4" subpath. It also added a re-export of Zod 3 from "zod/v3".
The idea is that these subpaths are "permalinks" to these associated versions that can be referenced by any library with a peer dependency on zod@>3.25.0 (including 4.x, and additional future majors beyond).
That's why this PR is using this pattern. The usage of Zod in this PR is idiomatic and consistent with the best practices described in my Library Authors writeup, which are already in use in the AI SDK, React Hook Form, and several others in the wild.
There was a problem hiding this comment.
Thanks for taking time to review!
| "peerDependencies": { | ||
| "@cfworker/json-schema": "^4.1.1" | ||
| "@cfworker/json-schema": "^4.1.1", | ||
| "zod": "^3.25 || ^4.0" |
There was a problem hiding this comment.
This PR does bump the minimum version to 3.25.0, so any users fro Zod 3.23.x or 3.24.x would need to bump their version.
You could categorize this as a breaking change, but I personally think bumping a peer dep to a new minor version does not constitute a breaking change on your part. There were no breaking changes between Zod 3.23 -> 3.25 so it's a one-line npm command for users to upgrade.
There are also far more Zod 3.25 & Zod 4 users (52m/wk downlods) than Zod 3.24 users (6m/wk) or Zod 3.23 users (5m/wk). The upside of merging this is far greater than the downside to users who are pinned on older versions. Feel free to tag me if you receive any pushback on this and I'll explain why the bump was necessary.
There was a problem hiding this comment.
Shouldn't these files actually be put into a subfolder, so that the full path would be src/vendor/zod-to-json-schema/? It would be problematic if we add another vendored library in the future.
5 participants
Motivation and Context
Add transparent Zod v3/v4 compatibility to the MCP TypeScript SDK, allowing users to install and use either version without any code changes or configuration. This addresses the need for the SDK to support multiple major versions of Zod in user applications.
The SDK exports v4 schemas by default, but the compatibility layer detects the Zod version at runtime and routes all schema operations (parsing, JSON Schema conversion, schema construction) to the appropriate implementation.
Borrowed openai's idea to vendor zod-to-json-schema locally, can be removed if the lib author ever merges their PR.
How Has This Been Tested?
Install the published version and test in your own app:
npm i @socotra/modelcontextprotocol-sdk # or pnpm i @socotra/modelcontextprotocol-sdkComprehensive Test Coverage
49 Test Suites | 1090 Tests (all passing)
User-facing APIs tested with both v3 and v4:
Internal utilities tested with v4 only:
Test Files Created
.v3.test.tsfiles demonstrating real Zod v3 usage patternstypes.jsBreaking Changes
None. This is purely additive:
Types of changes
Checklist
Additional context
Implementation Architecture
Compatibility Layer (
src/server/zod-compat.ts)isZ4Schema(),isZ4Object(),isZ3Object()safeParse(),safeParseAsync()objectFromShape(),normalizeObjectSchema()SchemaOutput<S>,SchemaInput<S>JSON Schema Routing (
src/server/zod-json-schema-compat.ts)Design Decisions